---
title: Hover Card
description: Using the hover-card machine in your project.
package: "@zag-js/hover-card"
---

An hover card allows sighted users to preview content available behind a link

<Resources pkg="@zag-js/hover-card" />

<Showcase id="HoverCard" />

**Features**

- Customize side, alignment, offsets
- Optionally render a pointing arrow
- Supports custom open and close delays
- Opens on hover only
- Ignored by screen readers

## Installation

To use the hover card machine in your project, run the following command in your
command line:

<CodeSnippet id="hover-card/installation.mdx" />

## Anatomy

To set up the hover card correctly, you'll need to understand its anatomy and
how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="hover-card" />

## Usage

First, import the hover card package into your project

```jsx
import * as hoverCard from "@zag-js/hover-card"
```

The hover card package exports two key functions:

- `machine` — The state machine logic for the hover card widget.
- `connect` — The function that translates the machine's state to JSX attributes
  and event handlers.

Next, import the required hooks and functions for your framework and use the
hover-card machine in your project 🔥

<CodeSnippet id="hover-card/usage.mdx" />

### Setting the initial state

To make an hover card open by default, set the `defaultOpen` property to `true`

```jsx {2}
const service = useMachine(hoverCard.machine, {
  defaultOpen: true,
})
```

### Listening for open state changes

When the hover card is `opened` or `closed`, the `onOpenChange` callback is
invoked.

```jsx {2-5}
const service = useMachine(hoverCard.machine, {
  onOpenChange(details) {
    // details => { open: boolean }
    console.log("hovercard is:", details.open ? "opened" : "closed")
  },
})
```

## Styling guide

Earlier, we mentioned that each hover card part has a `data-part` attribute
added to them to select and style them in the DOM.

```css
[data-part="trigger"] {
  /* styles for trigger */
}

[data-part="content"] {
  /* styles for content */
}
```

### Open and closed state

The hover card exposes a `data-state` attribute that can be used to style the
hover card based on its open-close state.

```css
[data-part="trigger"][data-state="open|closed"] {
  /* styles for open or closed state */
}

[data-part="content"][data-state="open|closed"] {
  /* styles for open or closed state */
}
```

### Arrow

Zag exposes some variable that can be used to style the arrow.

```css
[data-part="arrow"] {
  /* styles for arrow */
  --arrow-background: white;
  --arrow-size: 8px;
}
```

```css
[data-part="content"] {
  /* styles for content */
}
```

## Methods and Properties

### Machine Context

The hover card machine exposes the following context properties:

<ContextTable name="hover-card" />

### Machine API

The hover card `api` exposes the following methods:

<ApiTable name="hover-card" />

### Data Attributes

<DataAttrTable name="hover-card" />

### CSS Variables

<CssVarTable name="hover-card" />

## Accessibility

### Keyboard Interactions

The hover card is intended for mouse users only so will not respond to keyboard
navigation.
